Turnbull China Bikeride/Turnbull China Bikeride - Disc 2.iso/STUTTGART/FROMUTS/BLACKHOLE/!BlakHole2/!Help

Text File | 1993-02-23 | 32KB | 646 lines

                                 BLACK HOLE II
                                ===============

Introduction
============

This is an updated RISC OS 3 version of the original Black Hole. It is faster
and now uses the Filer Action windows to provide greater integration with
the operating system and an improved 'feel'.

Black Hole provides the following:
 * A quick and easy way of deleting files. All of the wipe options can be set
   from within Black Hole.
 * It provides wipe features not normally available, such as the ability to
   retain directories.
 * It can be configured to keep a backup copy of any file it deletes, for a
   specified length of time.
 * All operations are carried out in the background as much as possible. This
   means you can get on with other things while BlackHole grinds away at your
   disc.
 * It provides a facility for saving files from desktop applications into
   specified directories.
 * It contains a file find utility.
 * It puts a nice sprite on your iconbar which spins round and looks pretty.
 * Black Hole is fully compatible with Acorn's !Help.

Black Hole has many features. Do not be put off if it appears complicated.
It's actually very simple, and you don't need to understand most of it
anyway.

**************************** I M P O R T A N T ******************************

Black Hole requires a directory called the 'Bin Directory'. Normally this is
the directory !BlakHole2.BlackHole, but may have been changed by the person
who gave you the program. If this is the case, then Black Hole will
probably report an error the first time it is run informing you that the
Bin Directory cannot be found. What it then does is to revert to the default
Bin Directory and save this to disc so that the error does not occur again.
See below for more information about the Bin Directory. If you simply cannot
get the program to run (a very, very unlikely probability) then check that
the application contains all the files described at the end of this file, and
try deleting the files 'Options' and 'SaveOpts'.

*****************************************************************************

                            The Bin Directory
                           -------------------

Like all wastebin programs, Black Hole can be set up to keep copies of any
files you drag to it. These copies are kept in a directory which is referred
to throughout this file as the Bin Directory.
A few words about this may be useful:
1) Files copied to the bin directory are placed in a subdirectory called
xx_yy_zzzz where xx is the day of the month, yy is the month and zzzz is the
year. Clicking Select over the iconbar icon opens the directory for today if
it exists, otherwise the root bin directory is opened.
2) When copying to the bin directory, Black Hole will go by the fastest
possible route - i.e. it will rename files if possible as this is faster than
copying and then deleting. However, if 'Force' is not set, then Black Hole
must first copy and then delete files as Rename ignores the access status
of files. This results in two Filer Action windows appearing one after the
other.
3) Any files or directories placed in the ROOT bin directory which do not
have names of the form "xx_yy_zzz" will be deleted next time Black Hole
is run.

----------------------------------------------------------------------------

Pressing the menu button over the BlackHole icon produces a standard menu
with several options:

Info      ==> Leads to a window containing information about the program.

Config..      Opens a window containing the configuration. Files and
              directories dragged to the BlackHole icon will be wiped subject
              to these options. There are also options for controlling other
              aspects of the program. See below for an explanation.
              The Options window can also be opened by pressing the right
              mouse button over the iconbar icon.

Contents  ==> Leads to a submenu allowing you to perform five operations on
              the contents of the Bin Directory.
              These five options all have a submenu. This contains the entry
              'All' followed by the names of any subdirectories set up for
              one day's working. Selecting All makes the action apply to the
              whole bin. Selecting one directory applies to only that day.
              Clicking on the entry in the Contents menu is equivalent to
              selecting 'All'.
              If the bin directory is empty, this entry will appear in light
              grey and will read "No Contents"
              Destroy    : Unconditionally wipes everything. There is a
                           confirmation window before this happens.
              Count      : Counts the contents.
              Info       : Reads the contents of the Bin and displays their
                           names, sizes, and types in a window. Clicking on
                           a filename in this window will open the parent
                           directory of that file.
              Squash     : Uses the RISC OS 3 Squash module to compress all
                           the files in the bin, thus making them take up
                           less disc space. The file 'Squash' from inside
                           the !Squash application must be present in the
                           current library (ie %) (see user guide under
                           library).
              Open       : Will open the bin directory selected from the
                           submenu. Selecting 'All' will open all the
                           subdirectories.

Wipe Drive==> Leads to a window containing the names of any adfs floppy
              drives fitted, and also the RAM disc, if present. Selecting one
              of these will cause the disc in the selected drive to be wiped
              of all its contents. There is a confirmation window before this
              happens, where clicking on 'No' will abort the operation.
              If you want to rename the disc, the new name can be entered
              in the submenu off this menu. Leaving this submenu blank will
              keep the same name for the disc. This menu will also
              recognise Brian Brunswick's MemFS filer if it is present.

Auto Saver..  Opens the Auto File Saver window. See below for an explanation
              of this feature.

Find File ... Opens the File Finder window, which can be used to search
              a directory structure for all files of a particular name
              or type. See below for a fuller explanation.

Quit          Quits the Black Hole

-----------------------------------------------------------------------------

The Config Window:
==================

This window is divided into two sections. The options are contained within
the scrollable section of the window. The outside portion of the window
contains two buttons - click OK to close the window, or Save to store the
current settings as permanent defaults.

The scrollable panel is divided into four sections. These are:

 Default Wipe Options:
 ---------------------
  These icons control the way Black Hole deletes files dragged to its icon.
  Black Hole uses the standard RISC OS 3 Filer Action window so that a Black
  Hole wipe operation will appear the same as any other desktop delete
  operation.

  Confirm:
   Prompts for confirmation of all deletions.

  Force:
   Forces deletion of locked objects.

  Verbose:
   Displays information on each object deleted.

  Retain Structure:
   If this icon is selected, then only directory contents will be deleted.
   All directories will remain intact, even if empty.

 Copy Options:
 -------------
   These icons control the 'wastebin' aspect of Black Hole.

  Retain Copies:
   Turning this off disables the wastebin aspect of Black Hole - ie it will
   not copy any files to its bin directory.
   Dragging a file or selection of files to the Black Hole while holding down
   Ctrl will turn this option off for those files.

  Delete Copies After:
   If you use 'Retain Copies', then files are not actually deleted, they are
   just moved into the Bin directory where they will remain until you do
   something about it. This option allows Black Hole to do something about it
   for you. If you select this option, then files in the Bin Directory will
   be kept there for the specified number of days, then deleted for good.

  Bin Location
   The Black Hole Bin directory is, by default, the directory
    !BlakHole2.BlackHole
   but this can be changed if desired. To do this, enter the pathname of the
   directory you wish to use into this box. Pressing RETURN immediately or
   clicking on the OK icon will make your new directory the Bin Directory.
   Dragging a directory to the options window will insert the pathname of
   that directory as the new Bin Directory and make the change current.
   Leaving the box empty will cause the default to be restored.
   Clicking select on the iconbar icon opens the current Bin Directory.
   The 'Empty' or 'Occupied' message below the iconbar icon applies to this
   directory, as does the 'Delete Copies After' option, if the new bin
   location is saved permanently.

 Misc:
 -----
  Spin:
   When the pointer is over a BlackHole window or its iconbar icon, the icon
   will spin round. On an ARM 2 in some screen modes this can cause flicker
   which can be irritating. This option is therefore provided for those
   people who don't like their Black Holes to spin.

 Clock:
   Turning this on will cause a small digital clock to appear on the iconbar
   next to the pallette icon. This is here for gratuitous showing off reasons
   only. You can also select whether to have a 12 or 24 hour clock.

  Sprites:
   The iconbar sprites used for the animation of the Black Hole can be
   changed very easily. (Black Hole is supplied with three sets of sprites.)
   Clicking the left button over the arrow next to this option opens a menu
   containing the names of the current sprite files. Select one to change
   the sprites.
   To define your own sprites, you need a sprite file containing nine frames
   of animation named !black0 through !black8 inclusive. Mode 12 sprites
   should be 34 x 17 pixels. Mode 20 sprites should be 34 x 34. Save the
   sprite file into the directory !BlakHole2.Sprites and it will appear on
   the Sprites menu.
   The standard RISC OS 3 *IconSprites convention is used for these files;
   i.e. the same animation can have low res. (Mode 12), high res. (Mode 20)
   and high res. monochrome sprites defined. The Mode 12 sprites should be
   saved as whatever you want to call them, the mode 20 ones should have the
   same name with a 22 appended. Black Hole will ignore any files ending in
   22 or 23 on its sprite menu, but RISC OS 3 will automatically select the
   correct one for the current mode. The default sprites (BlakHole) are defined
   this way. If you select the 'Update on mode change' option, then Black Hole
   will automatically update its sprites to suit the new resolution when you
   change to a new screen mode, subject to a suitable sprite file being
   available.

  Use Fonts:
   Selecting this causes Black Hole to use an outline font for the text in
   its menus and the iconbar clock. In my opinion, these look far nicer than
   the normal system font and as they're built in to RISC OS 3, why shouldn't
   they be used? The fonts definitely look best in a hi-res mode so this icon
   is provided to allow you to turn them off if you don't like them.
   Remember that if you do use fonts, you will need a small font cache - 32K
   is more than adequate.

 Auto Saver Options:
 -------------------
 These two options refer to the Auto Saver part of Black Hole which is
 described more fully below.

 Confirm before Saving:
  This will ask whether you are sure before saving anything. It will also tell
  you if the file already exists.

 Open Destination when Saved:
  This will open the destination directory when a file is saved into it using
  the Auto Saver.

-----------------------------------------------------------------------------

The Auto Saver.
===============

How many times have you started to drag a file from the save box of some
application, only to find you can't see the directory where you want to put
the file? Worry no longer. The autosaver allows you to set up beforehand a
list of filetypes and which pathnames to save them to.

An example. Suppose you always save Text files into a directory called
adfs::4.$.Textfiles. Select the Autosaver option from BlackHole and type FFF
(the filetype for text files) in the Filetype box. Type the pathname into the
Destination box. From now on, if you drag a textfile from the "Save as:" box
of Edit (or any application which can output data as a textfile) to the
BlackHole icon, it will be saved to the specified pathname. (Note: a filename
must be specified in the application's Save As box.) This can be done for any
filetype.
In other words, you can specify a pathname for a particular file type. If you
then 'save' a file of that type 'into' Black Hole, it will stick the specified
pathname in front of the filename and save the file.

This only applies when you drag a file FROM THE SAVE BOX OF AN APPLICATION.

If you drag a file from a directory viewer to the Autosaver window, it's type
will be inserted in the window. Dragging a directory to the Autosaver window
inserts its pathname.

You can also type the name of the file type (eg Text instead of FFF),
but note that this is case sensitive. Clicking on the arrow button next to
this icon will open a filetype menu from which you can select one.

If there is no path set up for a filetype dragged to the icon, it will be
saved to the current Black Hole Bin directory.

If you have more than one path set up for one filetype, then the one used
will be EITHER the one currently displayed in the AutoSaver window (even if
it is not visible on screen) OR if no path for that filetype is displayed,
then it will be the one highest in the list.
If a file already exists with the pathname given, it will be overwritten.

To make the settings in this window permanent, click on the Save button.

-----------------------------------------------------------------------------

The File Finder.
================

The file finder can be used to find files (surprise!)
Enter the path you wish to search in the 'Search Path' icon. This directory
and all its subdirectories will be searched  for files and directories with
names and/or filetypes matching those specified in the 'Search For:' section.
Multiple search paths (including the names of floppy discs) can be specified
by separating them with a backslash (a "\"). For example, you could enter
adfs::4.$.Apps\adfs::4.$.Games. The filer will prompt for disc insertion if
necessary.

Similarly, you can enter multiple search names in the 'Name(s) :' box. Again
use "\" as a separator. A maximum of 10 names can be entered, and they can
contain wildcards. The wildcards accepted are the standard RISC OS ones -
# for any one character, * for zero or more characters.

If you want to search for one particular file type, this can also be entered.
This works both separately and in conjunction with the Name(s). If no type is
entered, all files matching the Name(s) will be listed.

Dragging a directory to this window will add it to the path list, putting a
"\" in if one is not already there.
Dragging a file to the window will make the type of that file the current
search type. The filetype menu can be opened by clicking on the arrow icon.

The button icons in this window control the following:

Case Sensistive: If this is selected, then the search becomes case sensitive,
                 i.e. entering 'Help' as the filename will find files called
                 'Help' but not 'help'.

Open Viewer:     Will open the directory viewer containing the found file.

List Details:    Will list the files found, their types and sizes in a window.
                 Clicking on a filename in this window will open the parent
                 directory of that file.

Use ArcFS on Archives:
ArcFS is a filing system which has been written (not by me) to allow easy
access to archive files produced by David Pilling's 'Spark' archiver program.
If you own ArcFS you can select this option and then Black Hole will use ArcFS
to search through archives just as if they were directories.
The module 'ArcFSMod' from inside !ArcFS must either be in memory, or be present
in the directory !System.Modules, otherwise this icon will be greyed out.
('Spark' is copyright David Pilling and has no connection with myself.)
('ArcFS' is copyright Mark Smith and also has no connection with me.  )

As an example - if you want to search the directories 'adfs::4.$.apps' and
'adfs::4.$.graphics' for any files of type FFF with names containing 'text':
Type
  adfs::4.$.apps\adfs::4.$.graphics
into the search path box. Type
  *text*
into the Name box and select case sensitivity as appropriate. Now type
  FFF (or Text)
into the type box. Finally hit RETURN or click on GO.

The GO button becomes an Abort button for the duration of the search. Clicking
on this button at any time during a search will stop the search and display
the results.

If you leave both the name and type boxes blank, then all the files in the
specified search path(s) will be listed - Black Hole defaults to a "*" for
the search name.

-----------------------------------------------------------------------------

Notes:
======

1) Rather than using Squash, which is rather slow, you may like to compress
   your Retained Copies by another method. This is most easily done if you
   own Computer Concept's Compression. You can simply make the Bin Directory
   a CFS directory. Provided CFS is loaded before Black Hole on bootup,
   everything will be OK. This has the added advantage that files are
   compressed as they are added to the bin.
   For example, you could make the bin directory
     CFS#adfs::IDEDisc4.$.!BlakHole2.BlackHole.

2) Dragging the contents of the Bin directory to the iconbar icon WILL delete
   them if force is off, but will not if force is on. This is because force
   MOVES files, but force off copies then deletes. If Retain Copies is off,
   or Ctrl is pressed, then they will be deleted whatever.

3) Black Hole treats DOS partitions as normal directories for all purposes.
   If a DOS partition is deleted with 'Retain Copies' set, then the files are
   retained but in a directory with the same name as the partition, not as
   a partition.

4) If you want to customize Black Hole to use fonts other than the defaults,
   then load the file 'Messages' into a text editor (eg !Edit) and change the
   relevant lines in there. It's self-explanatory and very easy really, honest.

5) Observant people may notice that the file finder searches backwards down
   a group of directories, i.e. if your root directory has five subdirectories
   such as !Boot, !Fonts, !System, !Scrap, and Apps, the file finder will
   search them in reverse order. This is simply because of the way it works
   and I've not bothered to change it because it means that almost everything
   gets searched before !Fonts, which really doesn't need searching anyway,
   and so the search can be manually aborted at this point.

-----------------------------------------------------------------------------

Brief Explanation of Contents of !BlakHole2.
============================================

!Boot and !Run are the usual stuff.

!Help is this file.

!RunImage, Init, Setup, and Overlay are the program - it's split into chunks so
I can get more program into the same memory.

!Sprites and !Sprites22 are the filer sprites.

BlackHole is the default bin directory.

icons contains the sprites used in the windows.

Messages contains the Help Text and other such nonsense.

Sprites contains the sprite files for the animation of the iconbar icon. By
default these are BlakHole, BlakHole22, and Recycle. There may be others...

Temp is a directory used when directory structure needs to be retained.

Templates are...... the templates!!

Options is where the Config. options are saved.

Saveopts is the options for the Auto Saver. You can alter this using Edit if
you like, just save a sample file to find out the format.

If these last two files are not present, Black Hole will use its own defaults
for all the options.

-----------------------------------------------------------------------------

Notes - The Sequel (more random ramblings)
==================

This program is far from perfect. The reasons for this are many and varied
and the word 'incompetence' appears in them frequently. A large part of it
is because I learnt to program RISC OS by staring vacantly at other people's
programs until the sugar of understanding began to crystallise in the
syrup of my brain. (Sorry, too much psychedelic music.)
By the way, I can strongly recommend the method of programming I use:
1) Decide what it is you want to do.
2) Find a program that already does it.
3) 'Adapt' the code in that program.
4) Have a coffee.
This works very successfully and probably explains why I've got three
apparrently identical procedures, each of which is absolutely crucial to the
program. Ho hum.
Please note, however, that this is not an admission of plagiarism.
Other people's programs are a great source of PRM-type information, and are
usually far more easily understandable than Acorn literature.

The next bit of this file is a load of boring pseudo-legal crap which I put
in because everybody else does, so it seemed like a good idea.

-----------------------------------------------------------------------------

Disclaimer:
===========

This program is supplied 'as is' with no guarantee of its suitability for any
purpose. I will not be held responsible for any loss of data occuring through
the use or misuse of this program. I will also not be held responsible for
anything else you may do after accidentally deleting your valuable files.
If you're worried about losing things, then use 'Retain Copies' - that's what
it's for.

-----------------------------------------------------------------------------

Public Domain Notice:
=====================

This software is Public Domain and may be freely copied and used, as long as
the following conditions are met:

a) That this notice is distributed unchanged with every copy.
b) That the application is supplied with unchanged versions of all the files
   described above.
   (If you do make modifications to any part of BlackHole, please do not
   distribute them without contacting me first, at the address below.)
c) No charge is made for the distribution. Public domain libraries may make
   a small charge to cover distribution costs. It is highly unethical, not
   to mention dishonest to make a charge for software which programmers
   have intended to be freely distributed, especially if none of that profit
   finds its way to the programmer.

All copyright is reserved. You may not use any part of this application in
any project which is to be sold for profit without my express permission
in writing.

If you wish to use pieces of my code in your own pd programs then please feel
free to do so, provided these programs are not intented for sale.
I say this mainly because my telling you not to do so would not stop you, but
also becasue I learned programming by nicking and splicing bits of other
people's programs, so why shouldn't you?

If you do use my code, a credit would be nice. Money would be even better.

Anyone out there feeling particularly generous can send me a £5.00 (ono)
registration fee and a disc, (well, actually a disc and a nice letter saying
how wonderful my program is would probably do the trick,) and I will send them
free upgrades whenever I write one, possibly accompanied by any PD applications
I can get my grubby little mitts on.

-----------------------------------------------------------------------------

Thanks go to:
=============

All the programmers who unknowingly taught me how to program RISC OS; I can't
afford a set of PRM's (and the RISC OS 3 ones aren't out yet) so looking at
other people's code was the quickest way to learn.
Brief mention of the people without whom BlackHole would not have existed.
(With addresses where these were included in their Help files.)

Robin Watts     - The finer details of one or two SYS calls and the
                  associated routines for extracting the useful data from
                  them were purloined from his excellent !Larger - 'Sticky
                  Backdrop Extraordinaire', which I spend most of my time
                  beta- testing for him. (I've got RISC OS 3, which has a
                  built-in sticky backdrop, but it's crap, so !Larger is a
                  most welcome burden on my hard disc.) Robin was also never
                  too busy to give advice or to let me peruse his PRMs.
                  (Well, hardly ever.....). The routines for doing the Config.
                  window as a composite window also came from Robin.
                  Robin's Addresses are:
                  217 Waterhouse Moor, Harlow, Essex CM18 6BW, OR
                  St. Catherine's College, Manor Road, Oxford OX1 3UJ
                  or by Janet: [e-mail]

James Miller    - Thanks to James for mailing me with a bug in the File Finder
                  and informing me of the existence of the Boot File Creation
                  message. (Why do I always find the bugs the day AFTER I
                  release the software? This must be nature's way of ensuring
                  that software always produces offspring - a new version is
                  always required to fix the bugs in the previous version.
                  Evolution in action!)

Emmet Spier     - Emmet's Help file said that he didn't mind people nicking
                  his code, provided he got a credit, so I wholeheartedly and
                  ruthlessly butchered out the code for a filetype menu from
                  his !Set-Type. Then I decided that it took up too much
                  memory so I vastly simplified it, with the result that it
                  now doesn't include all the nice little sprites. Anyway, the
                  bare bones of his routine are in this program somewhere.

Steve Singer    - I didn't copy any code from Steve, but it was he who
                  complained that he wouldn't even look at my proggy if the
                  iconbar icon didn't spin round. And he also wrote Bloxed,
                  a game which may be the future cause of failure in Finals
                  for half of St. Catherine' College. He also showed me the
                  NeXT workstation which was running the program which gave
                  me the inspiration for Black Hole. And now he tells me he
                  never uses Wastebin programs.....

-----------------------------------------------------------------------------

Differences between Black Hole and Black Hole II version 1.10½
==============================================================

The original Black Hole ran on RISC OS 2 and RISC OS 3. As RISC OS 3 is now
accepted as standard on Acorn machines I decided to make use of some of its
new features in this new version of the program.

1) All Filer operations are now run by Filer_Action. The advantages of this
are:
  i) A dramatic speed increase when deleting large numbers of files.
  ii) Any errors which occur are trapped by the filer and should not crash
  Black Hole as happened very occasionally in the original (I can't think of
  everything.....)
  iii) More than one operation can be carried out simultaneously.
The disadvantages are:
  i) When copying to the bin, Filer_Action ignores the access status of
  files. Thus if Force is off, you still get all the locked files copied
  although they aren't deleted. However, I don't anticipate many people
  using this program with Force off.
  ii) For Retain Structure, the original would simply not delete any
  directories. Filer_Action cannot do this, so the structure has first to be
  copied, then written back once the deletion has finished.
  iii) Copies cannot be squashed as they are copied. This version has a
  Squash option on a menu.

2) The file finder has been dramatically speeded up and ArcFS compatibililty
included. Wildcarded searches are now possible. Note: This version has been
speeded up relative to versions of BlakHole2 prior to 1.10.

3) DOS partitions are recognised and treated as directories.

4) The bin structure has been changed to have a separate subdirectory for
each day of use. This allows more organisation of your rubbish (which may or
may not be useful) and also allows the auto deletion to be much faster, which
will stop people from shouting at me.

5) Because people complained about my options and radio icons, I've taken
them out. The program now uses whichever icons are standard on your machine.

6) 3d icons have been adopted. I have no idea what the Acorn guidelines are,
so I've adopted those used by Computer Concepts and Simon Huntingdon's
Interface module, since Acorn seem to have copied their icons. (Note: No
relation between S.H. and CC is implied.......(got to cover myself!))

7) The Info window has got sillier.

8) I have added an option to use outline fonts in the menus. I like this, but
some people prefer consistency - that's why it's an option. Also it does NOT
look good in mode 12....

9) I have simplified the File Type menu. This ate up a large chunk of memory
which I decided I needed. And I never used it anyway... You can now type the
name of a filetype (eg 'Module' etc) into a 'Filetype' writeable icon.

10) The iconbar sprites change from low-res to high-res (and vice-versa)
automatically when you change mode (provided you select the option). This is
done simply by *IconSprites, which requires disc access so I made it optional.

11) A slightly more sensible (ie non-random) version numbering system has
been introduced.

12) When not doing anything, BlakHole2 takes up less than 1% of available
background time, even with the Clock and Spin selected.

13) Black Hole responds to the Task Manager's "Create Boot File" message. In
other words, if you save a Desktop Boot file from the Task Manager while
Black Hole is loaded, a line will be inserted in the file to run Black Hole.
Thus Black Hole will be run automatically on bootup.
(Thanks to James Miller for this one.)

-----------------------------------------------------------------------------

Music played while programming:
===============================

Too many to name all, but these and more:
Brian Eno, Magma, King Crimson, Amon Düül II, Jethro Tull, Genesis,
Roxy Music, The Soft Machine, The Incredible String Band, Ozric Tentacles,
Can, Caravan, Led Zeppelin, Van Der Graaf Generator, Deep Purple.....
This probably explains quite a lot. (Some of this stuff is simply not music
to work to. I feel I've comitted sacriledge and this program is it...)


                            The Fat German, 1992
                  (He's not fat and he's not German either)
              ==================================================

Mark Greenwood, 122 Miswell Lane, Tring, Herts. HP23 4EU
E-mail (Janet) : [e-mail] (Valid only until end of June 1993)